//+------------------------------------------------------------------+
//|                     FlameCanvas.mqh 火焰效果绘图画布类头文件     |
//|                版权所有 2000-2025, MetaQuotes Ltd.              |
//|                        官方网址: https://www.mql5.com            |
//+------------------------------------------------------------------+
#include "Canvas.h"               // 引入 2D 绘图画布基类 CCanvas
#include <Controls/Defines.h>     // 引入控件相关常量定义（如事件类型、消息标识）

//+------------------------------------------------------------------+
//| 渐变颜色描述结构体（用于定义渐变效果的颜色与位置）               |
//+------------------------------------------------------------------+
struct GRADIENT_COLOR
  {
   uint              clr;      // 颜色值（ARGB 格式，如 0xFFFF0000 表示红色，A 为透明度）
   uint              pos;      // 颜色在渐变范围内的位置（百分比，0~100，0 为起始端，100 为结束端）
  };

//+------------------------------------------------------------------+
//| 渐变尺寸描述结构体（用于定义渐变填充的宽度与位置）               |
//+------------------------------------------------------------------+
struct GRADIENT_SIZE
  {
   uint              size;     // 渐变填充宽度（相对于基准填充的百分比，如 100 表示与基准等宽）
   uint              pos;      // 尺寸变化的位置（相对于渐变长度的百分比，0~100）
  };

//+------------------------------------------------------------------+
//| CFlameCanvas 类                                                  |
//| 功能：MT5 火焰效果专用绘图画布类，基于 2D 画布实现动态火焰渲染   |
//| 继承关系：public CCanvas（基于 2D 绘图画布类，扩展火焰特效能力）  |
//| 核心特性：                                                      |
//|  1. 支持动态火焰动画生成（含颜色渐变、形态变化、帧刷新）          |
//|  2. 适配图表尺度（自动根据图表缩放比例调整火焰尺寸）              |
//|  3. 支持自定义火焰调色板、渐变效果及渲染范围                      |
//|  4. 响应图表事件（如缩放、尺寸变化，自动调整火焰显示）            |
//|  5. 可基于价格数据绘制“火焰云”效果（结合金融图表的价格波动）      |
//+------------------------------------------------------------------+
class CFlameCanvas : public CCanvas
  {
private:
   //--- 图表与火焰基础参数
   uint              m_bar_gap;           // K线间距（像素，控制火焰横向密度）
   uint              m_bar_width;         // K线宽度（像素，影响火焰基础尺寸计算）
   uint              m_chart_scale;       // 图表缩放等级（0~5，对应不同的显示精度）
   double            m_chart_price_min;   // 图表当前可见价格最小值（用于火焰纵向适配）
   double            m_chart_price_max;   // 图表当前可见价格最大值（用于火焰纵向适配）
   ENUM_TIMEFRAMES   m_timeframe;         // 关联图表的时间周期（默认当前周期 PERIOD_CURRENT）
   string            m_symbol;            // 关联图表的交易品种（默认当前品种 Symbol()）
   int               m_future_bars;       // 火焰向前延伸的K线数量（预测方向的火焰长度）
   int               m_back_bars;         // 火焰向后延伸的K线数量（历史方向的火焰长度）
   int               m_rates_total;       // 关联的K线数据总量（用于同步图表数据更新）
   uint              m_palette[256];      // 火焰调色板（256级颜色，对应火焰不同亮度的显示）
   uchar             m_flame[];           // 火焰计算缓冲区（存储每个像素的火焰亮度值，0~255）
   uint              m_time_redraw;       // 下次刷新火焰的时间戳（毫秒，控制动画帧率）
   uint              m_delay;             // 火焰帧刷新间隔（毫秒，默认50ms，值越小动画越流畅）

   //--- 火焰形态控制参数（定义火焰的边界与形态）
   datetime          m_tb1;               // 火焰边界1的起始时间（时间轴坐标）
   double            m_pb1;               // 火焰边界1的起始价格（价格轴坐标）
   datetime          m_te1;               // 火焰边界1的结束时间（时间轴坐标）
   double            m_pe1;               // 火焰边界1的结束价格（价格轴坐标）
   datetime          m_tb2;               // 火焰边界2的起始时间（时间轴坐标）
   double            m_pb2;               // 火焰边界2的起始价格（价格轴坐标）
   datetime          m_te2;               // 火焰边界2的结束时间（时间轴坐标）
   double            m_pe2;               // 火焰边界2的结束价格（价格轴坐标）

   //--- 火焰方程与渲染坐标参数（内部计算用）
   int               m_cloud_axis[100];   // 火焰云的中心轴坐标（控制火焰整体形态）
   double            m_a1;                // 火焰边界1的斜率参数（线性方程 y=a1*x+b1）
   double            m_b1;                // 火焰边界1的截距参数（线性方程 y=a1*x+b1）
   double            m_a2;                // 火焰边界2的斜率参数（线性方程 y=a2*x+b2）
   double            m_b2;                // 火焰边界2的截距参数（线性方程 y=a2*x+b2）
   int               m_xb1;               // 火焰边界1起始点的画布X坐标（像素）
   int               m_yb1;               // 火焰边界1起始点的画布Y坐标（像素）
   int               m_xe1;               // 火焰边界1结束点的画布X坐标（像素）
   int               m_ye1;               // 火焰边界1结束点的画布Y坐标（像素）
   int               m_xb2;               // 火焰边界2起始点的画布X坐标（像素）
   int               m_yb2;               // 火焰边界2起始点的画布Y坐标（像素）
   int               m_xe2;               // 火焰边界2结束点的画布X坐标（像素）
   int               m_ye2;               // 火焰边界2结束点的画布Y坐标（像素）

public:
   /**
    * @brief 构造函数：初始化火焰效果绘图画布实例
    * @details 调用父类 CCanvas 构造函数，初始化基础参数（如 K线间距、缩放等级、刷新间隔等默认值）
    */
                     CFlameCanvas(void);

   /**
    * @brief 析构函数：销毁火焰效果绘图画布实例
    * @details 自动调用 Destroy 方法，释放火焰缓冲区、调色板等资源，销毁 2D 画布
    */
                    ~CFlameCanvas(void);

   //--- 火焰画布创建与配置接口
   /**
    * @brief 创建火焰效果画布（绑定到图表，初始化火焰缓冲区与调色板）
    * @param name [in] 画布资源名称（用于标识图表上的位图对象）
    * @param time [in] 火焰起始时间（对应图表的时间轴起点）
    * @param future_bars [in] 火焰向前延伸的K线数量（>0，控制火焰在未来方向的长度）
    * @param back_bars [in] 火焰向后延伸的K线数量（>=0，控制火焰在历史方向的长度）
    * @return bool - 操作结果：true 表示画布创建与火焰初始化成功，false 表示失败（如资源分配失败）
    * @note 内部会自动获取图表尺寸、价格范围等参数，初始化火焰调色板（默认红色系）
    */
   bool              FlameCreate(const string name,const datetime time,const int future_bars,const int back_bars=0);

   /**
    * @brief 设置关联的K线数据总量（用于同步图表数据更新）
    * @param value [in] K线数据总量（>=0，通常设为 CopyRates 获取的有效数据量）
    * @note 当K线数量变化时，会自动调整火焰在时间轴上的位置
    */
   void              RatesTotal(const int value);

   //--- 火焰样式设置接口
   /**
    * @brief 设置火焰调色板（自定义火焰的颜色渐变范围）
    * @param clr [in] 火焰基准颜色（ARGB 格式，默认 0xFF0000 红色，会基于此生成256级渐变）
    * @note 调色板生成规则：前32级为透明（亮度0），后续从基准色逐渐过渡到白色（亮度255）
    */
   void              PaletteSet(uint clr=0xFF0000);

   //--- 火焰绘制接口
   /**
    * @brief 基于价格数据绘制“火焰云”效果（结合价格波动生成动态火焰）
    * @param prices [in] 价格数据数组（如收盘价数组，控制火焰云的中心轴形态）
    * @param width [in] 火焰云的基础宽度（像素，影响火焰横向覆盖范围）
    * @param lenght [in] 火焰云的长度（K线数量，控制火焰纵向延伸范围）
    * @note 内部会调用 CloudDraw 绘制渐变区域，再通过 FlameCalculate 生成火焰动画帧
    */
   void              FlameDraw(const double &prices[],const int width,const int lenght);

   /**
    * @brief 设置火焰的边界参数（定义火焰的形状与范围）
    * @param xb1 [in] 边界1起始时间（时间轴坐标）
    * @param yb1 [in] 边界1起始价格（价格轴坐标）
    * @param xe1 [in] 边界1结束时间（时间轴坐标）
    * @param ye1 [in] 边界1结束价格（价格轴坐标）
    * @param xb2 [in] 边界2起始时间（时间轴坐标）
    * @param yb2 [in] 边界2起始价格（价格轴坐标）
    * @param xe2 [in] 边界2结束时间（时间轴坐标）
    * @param ye2 [in] 边界2结束价格（价格轴坐标）
    * @note 边界1和边界2构成火焰的左右/上下范围，设置后会自动转换为画布像素坐标并更新火焰形态
    */
   void              FlameSet(datetime xb1,double yb1,datetime xe1,double ye1,datetime xb2,double yb2,datetime xe2,double ye2);

   //--- 图表事件处理接口
   /**
    * @brief 图表事件处理器（响应图表缩放、尺寸变化、自定义定时器等事件）
    * @param id [in] 事件ID（如 CHARTEVENT_CHART_CHANGE 表示图表变化，CHARTEVENT_CUSTOM 表示自定义事件）
    * @param lparam [in] 事件长整数参数（根据事件类型不同，含义不同）
    * @param dparam [in] 事件双精度参数（根据事件类型不同，含义不同）
    * @param sparam [in] 事件字符串参数（根据事件类型不同，含义不同）
    * @note 内部处理逻辑：
    *       - 图表缩放/尺寸变化：自动调整火焰尺寸与位置
    *       - 自定义定时器事件（1302）：刷新火焰动画帧
    */
   void              ChartEventHandler(const int id,const long &lparam,const double &dparam,const string &sparam);

protected:
   /**
    * @brief 调整火焰画布尺寸（适配图表尺寸变化）
    * @return bool - 操作结果：true 表示尺寸调整成功，false 表示调整失败（如参数无效）
    * @note 内部会更新火焰缓冲区大小、重新计算火焰边界坐标，保持火焰与图表的适配性
    */
   bool              Resize(void);

   /**
    * @brief 同步图表缩放参数（根据图表当前缩放等级调整火焰的K线间距与宽度）
    * @note 缩放等级对应规则：
    *       - 等级0：K线间距1px，宽度1px（最高密度）
    *       - 等级5：K线间距32px，宽度22px（最低密度）
    */
   void              ChartScale(void);

   /**
    * @brief 内部火焰参数初始化（基于边界坐标计算火焰形态方程参数）
    * @note 自动计算 m_a1/m_b1（边界1线性方程）、m_a2/m_b2（边界2线性方程），为火焰绘制提供基础
    */
   void              FlameSet(void);

   /**
    * @brief 绘制价格关联的“火焰云”渐变区域（核心绘制逻辑）
    * @param prices [in] 价格数据数组（控制火焰云的中心轴）
    * @param width [in] 火焰云基础宽度（像素）
    * @param lenght [in] 火焰云长度（K线数量）
    * @param size [in] 渐变尺寸数组（定义火焰云宽度随位置的变化）
    * @param gradient [in] 渐变颜色数组（定义火焰云的颜色过渡）
    * @param t_level [in] 透明度等级（0~255，默认255完全不透明）
    * @param custom_gradient [in] 是否使用自定义渐变（true 用传入的 gradient，false 用默认渐变）
    * @note 内部通过 GradientVertical 绘制纵向渐变区域，构成火焰云的基础形态
    */
   void              CloudDraw(const double &prices[],const int width,const int lenght,GRADIENT_SIZE &size[],GRADIENT_COLOR &gradient[],const uchar t_level=255,const bool custom_gradient=true);

   /**
    * @brief 绘制基础火焰形态（基于渐变尺寸与颜色生成静态火焰）
    * @param width [in] 火焰基础宽度（像素）
    * @param lenght [in] 火焰长度（K线数量）
    * @param size [in] 渐变尺寸数组（控制火焰宽度变化）
    * @param gradient [in] 渐变颜色数组（控制火焰颜色过渡）
    * @note 绘制完成后需调用 FlameCalculate 生成动态火焰动画
    */
   void              FlameDraw(const int width,const int lenght,GRADIENT_SIZE &size[],GRADIENT_COLOR &gradient[]);

   /**
    * @brief 绘制纵向渐变填充区域（火焰云/火焰的基础渐变效果）
    * @param xb [in] 渐变区域的起始X坐标（像素）
    * @param xe [in] 渐变区域的结束X坐标（像素）
    * @param yb1 [in] 左侧渐变边界的起始Y坐标（像素）
    * @param ye1 [in] 左侧渐变边界的结束Y坐标（像素）
    * @param yb2 [in] 右侧渐变边界的起始Y坐标（像素）
    * @param ye2 [in] 右侧渐变边界的结束Y坐标（像素）
    * @param gradient [in] 渐变颜色数组（定义从左到右/上到下的颜色过渡）
    * @note 内部通过 GradientVerticalLine 逐列绘制纵向渐变，形成平滑的区域填充
    */
   void              GradientVertical(const int xb,const int xe,const int yb1,const int ye1,const int yb2,const int ye2,const GRADIENT_COLOR &gradient[]);

   /**
    * @brief 绘制单条纵向渐变线（火焰的列级渐变单元）
    * @param x [in] 渐变线的X坐标（像素，垂直于Y轴）
    * @param y1 [in] 渐变线的起始Y坐标（像素）
    * @param y2 [in] 渐变线的结束Y坐标（像素）
    * @param gradient [in] 渐变颜色数组（定义从 y1 到 y2 的颜色过渡）
    * @note 为 GradientVertical 提供基础绘制单元，逐像素填充渐变颜色
    */
   void              GradientVerticalLine(int x,int y1,int y2,const GRADIENT_COLOR &gradient[]);

   /**
    * @brief 绘制单条双色纵向渐变线（简化版渐变，仅两种颜色过渡）
    * @param x [in] 渐变线的X坐标（像素）
    * @param y1 [in] 渐变线的起始Y坐标（像素）
    * @param y2 [in] 渐变线的结束Y坐标（像素）
    * @param clr1 [in] 起始颜色（ARGB 格式）
    * @param clr2 [in] 结束颜色（ARGB 格式）
    * @note 用于快速绘制简单渐变效果，性能优于多色渐变
    */
   void              GradientVerticalLineMonochrome(int x,int y1,int y2,uint clr1,uint clr2);

   /**
    * @brief 生成动态火焰的基础形态（随机生成火焰边界与中心轴）
    * @note 内部通过随机数生成火焰的斜率、振幅等参数，构建多样化的火焰形态
    */
   void              FlameCreate(void);

   /**
    * @brief 计算火焰动画帧（更新火焰缓冲区的亮度值，实现动态燃烧效果）
    * @note 核心逻辑：基于上一帧的亮度值，通过扩散算法计算当前帧，模拟火焰的飘动与燃烧
    */
   void              FlameCalculate(void);

   /**
    * @brief 设置延迟执行（用于图表事件处理中的防抖，避免频繁刷新）
    * @param value [in] 延迟时间（毫秒，最小10ms，低于10ms会被忽略）
    * @note 内部通过循环等待实现延迟，确保图表参数稳定后再更新火焰
    */
   void              Delay(const uint value);
  };
//+------------------------------------------------------------------+